/*

 * Licensed to the Apache Software Foundation (ASF) under one

 * or more contributor license agreements.  See the NOTICE file

 * distributed with this work for additional information

 * regarding copyright ownership.  The ASF licenses this file

 * to you under the Apache License, Version 2.0 (the

 * "License"); you may not use this file except in compliance

 * with the License.  You may obtain a copy of the License at

 *

 *     http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.bff.gaia.unified.sdk.transforms.display;



import com.bff.gaia.unified.sdk.options.PipelineOptions;

import com.bff.gaia.unified.sdk.transforms.PTransform;



/**

 * Marker interface for {@link PTransform PTransforms} and components to specify display data used

 * within UIs and diagnostic tools.

 *

 * <p>Display data is registered by overriding {@link #populateDisplayData(DisplayData.Builder)} in

 * a component which implements {@code HasDisplayData}. Display data is available for {@link

 * PipelineOptions} and {@link PTransform} implementations.

 *

 * <pre><code>{@literal @Override}

 * public void populateDisplayData(DisplayData.Builder builder) {

 *  super.populateDisplayData(builder);

 *

 *  builder

 *     .include(subComponent)

 *     .add(DisplayData.item("minFilter", 42))

 *     .addIfNotDefault(DisplayData.item("useTransactions", this.txn), false)

 *     .add(DisplayData.item("topic", "projects/myproject/topics/mytopic")

 *       .withLabel("Pub/Sub Topic"))

 *     .add(DisplayData.item("serviceInstance", "myservice.com/fizzbang")

 *       .withLinkUrl("http://www.myservice.com/fizzbang"));

 * }

 * </code></pre>

 *

 * <p>Display data is optional and may be collected during pipeline construction. It should only be

 * used for informational purposes. Tools and components should not assume that display data will

 * always be collected, or that collected display data will always be displayed.

 *

 * @see #populateDisplayData(DisplayData.Builder)

 */

public interface HasDisplayData {

  /**

   * Register display data for the given transform or component.

   *

   * <p>{@code populateDisplayData(DisplayData.Builder)} is invoked by Pipeline runners to collect

   * display data via {@link DisplayData#from(HasDisplayData)}. Implementations may call {@code

   * super.populateDisplayData(builder)} in order to register display data in the current namespace,

   * but should otherwise use {@code subcomponent.populateDisplayData(builder)} to use the namespace

   * of the subcomponent.

   *

   * @param builder The builder to populate with display data.

   * @see HasDisplayData

   */

  void populateDisplayData(DisplayData.Builder builder);

}